/*
 * Copyright (C) 2006 Johan Maasing johan at zoom.nu Licensed under the Apache
 * License, Version 2.0 (the "License"); you may not use this file except in
 * compliance with the License. You may obtain a copy of the License at
 * http://www.apache.org/licenses/LICENSE-2.0 Unless required by applicable law
 * or agreed to in writing, software distributed under the License is
 * distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
 * KIND, either express or implied. See the License for the specific language
 * governing permissions and limitations under the License.
 */
package nu.zoom.catonine.tail;

import java.io.Serializable;
import java.util.List;

/**
 * Listens to events from the tailer.
 * 
 * @author "Johan Maasing" &lt;johan@zoom.nu&gt;
 */
public interface TailerListener {

	/**
	 * The tailer has discovered new lines. Notice! The tailer may send several
	 * LogEntries with the same position. This might for example be the case if
	 * the last bytes of a file is scanned before the the end or start-marker is
	 * discovered. In other words. The tailer may send "updates" of log entries
	 * by calling this method. Listeners need to look at the position in the log
	 * entry to determine if this is an update or an "append".
	 * 
	 * @param lines
	 *            The new lines the tailer has discovered in the tail source.
	 */
	public void lines(TailerLinesEvent lines);

	/**
	 * The tailer is busy doing some work.
	 */
	public void tailerWorking();

	/**
	 * The tailer has stopped working and has become idle.
	 */
	public void tailerIdle();

	/**
	 * Inform listeners that the tailer has stopped following its file. The
	 * tailer is now dormant and will need to be restarted.
	 */
	public void tailerStopped();

	/**
	 * Inform listeners that the tailer has been reset and any lines from this
	 * tailer has been invalidated. Listeners should ignore anything this tailer
	 * has produced since the tailer will restart parsing the tailed file. This
	 * is used to signal that the tailed file has been reset or that the tailing
	 * rules have changed and the file needs to be re-parser.
	 */
	public void tailerHasBeenReset();

	/**
	 * Event class used by the tailer when informing listeners about events.
	 * 
	 * @author "Johan Maasing" &lt;johan@zoom.nu&gt;
	 * 
	 */
	public class TailerEvent {
		/**
		 * The tailer that issued the event.
		 */
		public Tailer source;
	}

	/**
	 * Event when tailer has read new LogEntries from a file.
	 * 
	 * @author "Johan Maasing" &lt;johan@zoom.nu&gt;
	 * 
	 */
	public class TailerLinesEvent extends TailerEvent {
		/**
		 * The new or updated entries from the tailer. Notice that tailer
		 * implementations only guarantee the chronological order of events in
		 * the list. Some events may have the same offset i.e. position in the
		 * file. The later event in the list is an update of the previous event
		 * with the same offset.
		 */
		public List<LogEntry> entries;
	}

	/**
	 * A log entry that the tailer has extracted from the file it is following.
	 */
	public class LogEntry implements Serializable {
		private static final long serialVersionUID = 1L;
		public final long position;
		public final String content;

		public LogEntry(final long position, final String content) {
			this.position = position;
			this.content = content;
		}
	}
}
